<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<HTML LANG="EN-US">
<HEAD>
<TITLE>VT100.net: VT330/VT340 Programmer Reference Manual</TITLE>
<LINK HREF="vt330.css" TYPE="text/css" REL="stylesheet">
</HEAD>
<BODY>
<DIV CLASS="navbar"><A HREF="http://vt100.net/"><IMG CLASS="button" SRC="vt100.net-logo.png" ALT="VT100.net" HEIGHT="16" WIDTH="102"></A> VT330/VT340 Programmer Reference Manual Volume 2: Graphics Programming<TABLE WIDTH="100%">
<COL SPAN="3" WIDTH="33%">
<TBODY>
<TR>
<TD ALIGN="LEFT"><A HREF="chapter3.html">Chapter 3</A></TD>
<TD ALIGN="CENTER"><A HREF="contents.html">Contents</A></TD>
<TD ALIGN="RIGHT"><A HREF="chapter5.html">Chapter 5</A></TD>
</TR>
</TBODY>
</TABLE>
<HR></DIV>
<H1 ID="S4"><SPAN CLASS="chapnum">4</SPAN> Position Command</H1>
<P>Position commands let you move the active screen position without writing.
There are four basic command options.</P>
<UL>
<LI>Set position arguments</LI>
<LI>Position stack options</LI>
<LI>Temporary write control options</LI>
<LI>Select graphics page</LI>
</UL>
<H2 ID="S4.1">Set Position Arguments</H2>
<P>These arguments let you move the cursor to a new position on the screen, before
you use other ReGIS commands. You can specify the cursor position in
one of four formats.</P>
<UL>
<LI>Absolute</LI>
<LI>Relative</LI>
<LI>Absolute/relative</LI>
<LI>Pixel vector offset</LI>
</UL>
<H3 ID="S4.1.1">Absolute Position</H3>
<P>You can use absolute X- and Y-coordinates to define a new cursor position. You
can use three forms of this command.</P>
<DIV CLASS="example"><TABLE CLASS="padded">
<THEAD>
<TR>
<TH CLASS="first">X and Y Value</TH>
<TH>X Value Only</TH>
<TH>Y Value Only</TH>
</TR>
</THEAD>
<TBODY>
<TR>
<TD CLASS="first">P[X,Y]</TD>
<TD>[X]</TD>
<TD>[,Y]</TD>
</TR>
</TBODY>
</TABLE></DIV>
<P>where</P>
<DIV CLASS="example"><P><B>P</B> identifies a position command.</P>
<P><B>[X,Y]</B> specify new X- and Y-coordinates.</P>
<P><B>[X]</B> specifies a new X-coordinate (with the Y-coordinate unchanged).</P>
<P><B>[,Y]</B> specifies a new Y-coordinate (with the X-coordinate unchanged).</P></DIV>
<P><A HREF="#F4-1">Figure 4-1</A> shows examples of how to use each form to move the graphics cursor
around the screen.</P>
<TABLE ID="F4-1" CLASS="figure" WIDTH="100%">
<CAPTION>Figure 4-1 Examples of Absolute Position Commands</CAPTION>
<COL ALIGN="CENTER">
<TBODY>
<TR>
<TD><IMG SRC="ma-0669-83.png" ALT=""></TD>
</TR>
<TR>
<TD><TABLE CLASS="command-example" FRAME="BORDER" RULES="GROUPS" CELLSPACING="0" CELLPADDING="8">
<COL ALIGN="RIGHT">
<COL ALIGN="LEFT">
<TBODY>
<TR>
<TD COLSPAN="2" ALIGN="CENTER">COMMANDS</TD>
</TR>
</TBODY>
<TBODY>
<TR VALIGN="TOP">
<TD>(1)<BR>(2)<BR>(3)</TD>
<TD>P[200,200]<BR>[300]<BR>[,400]</TD>
</TR>
<TR>
<TD COLSPAN="2" ALIGN="LEFT"><P>NOTE:<BR>
Once P is specified, it is not needed again,<BR>
unless another type of command (such as<BR>
a screen command) comes between<BR>
bracketed move values.</P></TD>
</TR>
</TBODY>
</TABLE></TD>
</TR>
</TBODY>
</TABLE>
<H3 ID="S4.1.2">Relative Position</H3>
<P>You can use positive (+) and negative (-) values to define a new cursor position.
Relative values always start with a plus (+) or minus (-) sign. The terminal
adds or subtracts the relative value from the current cursor coordinates. The
result is the new cursor position.</P>
<P>A wraparound can occur in relative positioning, but only when you specify a
value that exceeds the limits of the 16-bit integer arithmetic available to
ReGIS. For example, suppose the cursor position is at [100,100], and you give
a command of P[+100,-101]. The new position is a relative value of [200,-1],
with no cursor wraparound.</P>
<P>There are eight possible forms of the relative positioning argument, using different
combinations of positive (+) and negative (-) coordinates. You can specify
one or both coordinates.</P>
<DIV CLASS="example"><TABLE CLASS="padded">
<TBODY>
<TR>
<TD CLASS="first">P[+X,+Y]</TD>
<TD>P[+X,-Y]</TD>
<TD>P[-X,+Y]</TD>
<TD>P[-X,-Y]</TD>
</TR>
<TR>
<TD CLASS="first">P[+X]</TD>
<TD>P[-X]</TD>
<TD>P[,+Y]</TD>
<TD>P[,-Y]</TD>
</TR>
</TBODY>
</TABLE></DIV>
<P><A HREF="#F4-2">Figure 4-2</A> shows examples of how to use each form to move the graphics cursor
around the screen.</P>
<TABLE ID="F4-2" CLASS="figure" WIDTH="100%">
<CAPTION>Figure 4-2 Examples of Relative Position Move Commands</CAPTION>
<COL ALIGN="CENTER">
<TBODY>
<TR>
<TD><IMG SRC="ma-0670-83.png" ALT=""></TD>
</TR>
<TR>
<TD><TABLE CLASS="command-example" FRAME="BORDER" RULES="GROUPS" CELLSPACING="0" CELLPADDING="8">
<COL ALIGN="RIGHT">
<COL ALIGN="LEFT">
<TBODY>
<TR>
<TD COLSPAN="2" ALIGN="CENTER">COMMANDS</TD>
</TR>
</TBODY>
<TBODY>
<TR VALIGN="TOP">
<TD>(1)<BR>(2)<BR>(3)<BR>(4)<BR>(5)<BR>(6)<BR>(7)<BR>(8)</TD>
<TD>P[+100,+50]<BR>[+50,-100]<BR>[-100,-100]<BR>[-150,+250]<BR>[+100]<BR>[,+150]<BR>[-125]<BR>[,-75]</TD>
</TR>
<TR>
<TD COLSPAN="2" ALIGN="LEFT"><P>NOTE:<BR>
Once P is specified, it is not needed again,<BR>
unless another type of command (such as<BR>
a screen command) comes between<BR>
bracketed move values.</P></TD>
</TR>
</TBODY>
</TABLE></TD>
</TR>
</TBODY>
</TABLE>
<H3 ID="S4.1.3">Absolute/Relative Position</H3>
<P>You can use a combination of absolute and relative X- and Y-coordinate values
to define a new cursor position. There are two forms of this command.</P>
<UL>
<LI>Specify an absolute X value with a relative Y value.</LI>
<LI>Specify a relative X value with an absolute Y value.</LI>
</UL>
<P>The formats for these commands are a combination of the formats for the absolute
and relative positioning arguments. See the two previous sections. <A HREF="#F4-3">Figure
4-3</A> shows examples of how to use both forms to move the cursor around the screen.</P>
<TABLE ID="F4-3" CLASS="figure" WIDTH="100%">
<CAPTION>Figure 4-3 Examples of Absolute/Relative Move Commands</CAPTION>
<COL ALIGN="CENTER">
<TBODY>
<TR>
<TD><IMG SRC="ma-0671-83.png" ALT=""></TD>
</TR>
<TR>
<TD><TABLE CLASS="command-example" FRAME="BORDER" RULES="GROUPS" CELLSPACING="0" CELLPADDING="8">
<COL ALIGN="RIGHT">
<COL ALIGN="LEFT">
<TBODY>
<TR>
<TD COLSPAN="2" ALIGN="CENTER">COMMANDS</TD>
</TR>
</TBODY>
<TBODY>
<TR VALIGN="TOP">
<TD>(1)<BR>(2)<BR>(3)<BR>(4)</TD>
<TD>P[300,-100]<BR>[600,+175]<BR>[-200,400]<BR>[+100,50]</TD>
</TR>
<TR>
<TD COLSPAN="2" ALIGN="LEFT"><P>NOTE:<BR>
Once P is specified, it is not needed again,<BR>
unless another type of command (such as<BR>
a screen command) comes between<BR>
bracketed move values.</P></TD>
</TR>
</TBODY>
</TABLE></TD>
</TR>
</TBODY>
</TABLE>
<H3 ID="S4.1.4">Pixel Vector Offset Position</H3>
<P>You can use pixel vector (PV) values to define a new cursor position. <A HREF="chapter1.html">Chapter 1</A>
describes pixel vectors. Pixel vectors move the cursor relative to the current cursor position.</P>
<P>Each PV value (0 through 7) selects a different direction of movement. <A HREF="#F4-4">Figure
4-4</A> shows these directions.</P>
<P>This command uses the current PV multiplication factor. There are two ways to
change this factor.</P>
<UL>
<LI>with a write control command</LI>
<LI>with a temporary write control option</LI>
</UL>
<P>The PV factor defined by the temporary write control option only stays in effect
until you use a new key letter (including a new P command key letter) or
another temporary write control option.</P>
<P>You use the following format for the PV offset positioning argument.</P>
<P CLASS="example">P&lt;PV value&gt;</P>
<P>where</P>
<P CLASS="example"><B>&lt;PV value&gt;</B> is one or more PV values defining movement. These PV values
use the current PV multiplication factor in effect.</P>
<TABLE ID="F4-4" CLASS="figure" WIDTH="100%">
<CAPTION>Figure 4-4 PV Direction Values</CAPTION>
<COL ALIGN="CENTER">
<TBODY>
<TR>
<TD><IMG SRC="ma-0654-83.png" ALT=""></TD>
</TR>
</TBODY>
</TABLE>
<P>You use the following format to change the PV multiplication factor with a
temporary write control option.</P>
<P CLASS="example">P(W(M&lt;multiplication factor&gt;))&lt;PV value&gt;</P>
<P>where</P>
<DIV CLASS="example"><P><B>W</B> identifies a write control option.</P>
<P><B>M</B> identifies a PV multiplication suboption.</P>
<P><B>&lt;multiplication factor&gt;</B> is a numeric value to use for the temporary PV
multiplication factor.</P>
<P><B>&lt;PV value&gt;</B> is one or more PV values defining movement. These PV values
use the temporary PV multiplication factor.</P></DIV>
<P><A HREF="#F4-5">Figure 4-5</A> shows examples of how to move the cursor around the screen with
pixel vectors. The examples use a temporary write control option to define a
PV multiplication factor.</P>
<TABLE ID="F4-5" CLASS="figure" WIDTH="100%">
<CAPTION>Figure 4-5 Examples of PV Move Commands</CAPTION>
<COL ALIGN="CENTER">
<TBODY>
<TR>
<TD><IMG SRC="ma-0672-83.png" ALT=""></TD>
</TR>
<TR>
<TD><TABLE CLASS="command-example" FRAME="BORDER" RULES="GROUPS" CELLSPACING="0" CELLPADDING="8">
<COL ALIGN="RIGHT">
<COL ALIGN="LEFT">
<TBODY>
<TR>
<TD COLSPAN="2" ALIGN="CENTER">COMMANDS</TD>
</TR>
</TBODY>
<TBODY>
<TR VALIGN="TOP">
<TD>&nbsp;<BR>(1)<BR>(2)<BR>(3)<BR>(4)</TD>
<TD>P(W(M100))<BR>77<BR>6<BR>444<BR>11</TD>
</TR>
<TR>
<TD COLSPAN="2" ALIGN="LEFT"><P>NOTE:<BR>
Once P is specified, it is not needed again,<BR>
unless another type of command (such as<BR>
a screen command) comes between<BR>
bracketed move values.</P></TD>
</TR>
</TBODY>
</TABLE></TD>
</TR>
</TBODY>
</TABLE>
<H2 ID="S4.2">Position Stack Options</H2>
<P>A <DFN>position stack</DFN> is a set of coordinate positions that ReGIS uses in sequence.
These options let you move the cursor to several positions in a single command.
As ReGIS performs the command, the cursor moves to each position in
the stack.</P>
<P>There are two types of position stacks, bounded and unbounded. Both types
include at least one start (or begin) command and one end command. However,
the start commands work differently in bounded and unbounded position
stacks.</P>
<P>You can embed other commands between pairs of start and end commands.
For example, you can embed several vector (V) commands between the start
and end commands.</P>
<H3 ID="S4.2.1">Bounded Position Stack &#8211; (B) and (E)</H3>
<P>You use a bounded position stack to return the cursor position to a specific
starting point at the end of the command. The bounded position stack works by
pushing the current cursor position onto the stack, then popping the position
off where appropriate.</P>
<P>You use the following format for a bounded position stack option.</P>
<P CLASS="example">P(B)&lt;embedded options&gt;(E)</P>
<P>where</P>
<DIV CLASS="example"><P><B>(B)</B> saves the current active position. (Pushes the position onto the stack.)</P>
<P><B>&lt;embedded options&gt;</B> are the position, vector, curve, and other command
options you use in the bounded position stack.</P>
<P><B>(E)</B> returns the active position to the coordinates saved by the last <B>(B)</B> option.
(Pops the position off the stack.)</P></DIV>
<P>You can save up to 16 positions in a stack. That is, you can use 16 (B)s and 16
corresponding (E)s in a stack. Remember, for each (B) pushing a position onto
the stack, there must be a corresponding (E) to pop the position off.</P>
<P CLASS="note">NOTE: The terminal saves position values during bounded and unbounded
stack options for position (P) commands and vector (V) commands (<A HREF="chapter5.html">Chapter 5</A>).
The maximum number of unended, saved positions (including all save commands)
is 16. However, for compatibility with other ReGIS products, use a
maximum of eight.</P>
<P><A HREF="#F4-6">Figure 4-6</A> shows an example of how to build a simple graphic image with a
bounded position stack. The example includes vector (V) and curve (C) commands.
See Chapters <A HREF="chapter5.html">5</A> and <A HREF="chapter6.html">6</A> for information on vector and curve commands.</P>
<TABLE ID="F4-6" CLASS="figure" WIDTH="100%">
<CAPTION>Figure 4-6 Building an Image with a Bounded Position Stack</CAPTION>
<COL ALIGN="CENTER">
<TBODY>
<TR>
<TD><IMG SRC="ma-0673-83.png" ALT=""></TD>
</TR>
<TR>
<TD><TABLE CLASS="command-example" FRAME="BORDER" RULES="GROUPS" CELLSPACING="0" CELLPADDING="8">
<COL ALIGN="RIGHT">
<COL ALIGN="LEFT">
<TBODY>
<TR>
<TD COLSPAN="2" ALIGN="CENTER">COMMANDS</TD>
</TR>
</TBODY>
<TBODY>
<TR VALIGN="TOP">
<TD>(1)<BR>(2)<BR>(3)<BR>(4)<BR>(5)<BR>(6)<BR>(7)<BR>(8)<BR>(9)</TD>
<TD>P[400,250]<BR>(B)<BR>[+100,-100]<BR>V[,+200]<BR>[-200]<BR>[,-200]<BR>[+200]<BR>P(E)<BR>C[+100]</TD>
</TR>
<TR>
<TD COLSPAN="2" ALIGN="LEFT"><P>NOTE:<BR>
Once a command letter is specified,<BR>
it does not need to be respecified,<BR>
unless another type of command comes<BR>
between command option values.</P></TD>
</TR>
</TBODY>
</TABLE></TD>
</TR>
</TBODY>
</TABLE>
<H3 ID="S4.2.2">Unbounded Position Stack &#8211; (S) and (E)</H3>
<P>The difference between an unbounded and a bounded position stack is that the
active position does not move at the end of an unbounded stack. An unbounded stack
begins with an (S) option rather than a (B) option. The (S) pushes a
dummy, or nonexistent position onto the position stack. The (E) pops this
nonexistent position off the stack, leaving the active position at the position
specified before the (E) option.</P>
<P>You use the following format for an unbounded stack command.</P>
<P CLASS="example">P(S)&lt;embedded options&gt;(E)</P>
<P>where</P>
<DIV CLASS="example"><P><B>(S)</B> saves a dummy location. (Pushes the dummy location onto the position
stack.)</P>
<P><B>&lt;embedded options&gt;</B> are the position, vector, curve, and other command
options you use in the unbounded stack.</P>
<P><B>(E)</B> pops the dummy position off the stack. The active position does not move.</P></DIV>
<P><A HREF="#F4-7">Figure 4-7</A> shows an unbounded position stack with the same vector (V) and
curve (C) commands used in the bounded position stack in <A HREF="#F4-6">Figure 4-6</A>. Figures
<A HREF="#F4-6">4-6</A> and <A HREF="#F4-7">4-7</A> show the difference in effect between bounded and unbounded
stacks.</P>
<P>The unbounded stack option is for symmetry with other command types (such
as curve commands) that can use bounded and unbounded stacks.</P>
<TABLE ID="F4-7" CLASS="figure" WIDTH="100%">
<CAPTION>Figure 4-7 Building an Image with an Unbounded Position Stack</CAPTION>
<COL ALIGN="CENTER">
<TBODY>
<TR>
<TD><IMG SRC="ma-0674-83.png" ALT=""></TD>
</TR>
<TR>
<TD><TABLE CLASS="command-example" FRAME="BORDER" RULES="GROUPS" CELLSPACING="0" CELLPADDING="8">
<COL ALIGN="RIGHT">
<COL ALIGN="LEFT">
<TBODY>
<TR>
<TD COLSPAN="2" ALIGN="CENTER">COMMANDS</TD>
</TR>
</TBODY>
<TBODY>
<TR VALIGN="TOP">
<TD>(1)<BR>(2)<BR>(3)<BR>(4)<BR>(5)<BR>(6)<BR>(7)<BR>(8)<BR>(9)</TD>
<TD>P[400,250]<BR>(S)<BR>[+100,-100]<BR>V[,+200]<BR>[-200]<BR>[,-200]<BR>[+200]<BR>P(E)<BR>C[+100]</TD>
</TR>
<TR>
<TD COLSPAN="2" ALIGN="LEFT"><P>NOTE:<BR>
Once a command letter is specified,<BR>
it does not need to be respecified,<BR>
unless another type of command comes<BR>
between command option values.</P></TD>
</TR>
</TBODY>
</TABLE></TD>
</TR>
</TBODY>
</TABLE>
<H2 ID="S4.3">Select Graphics Page &#8211; P</H2>
<P>This option lets you move the graphics cursor from one page to another. You
can only use this option when you use a single session on the terminal, not
dual sessions. When you use a single session, the terminal has two pages of
graphics page memory available, each 800 &times; 480 pixels.</P>
<P CLASS="example">P(P&lt;0 or 1&gt;)</P>
<P>where</P>
<DIV CLASS="example"><P><B>P</B> identifies the select graphics page option.</P>
<P><B>0</B> moves the cursor to the first graphics page.</P>
<P><B>1</B> moves the cursor to the second graphics page.</P></DIV>
<P>The terminal ignores values other than 0 and 1. Both the input cursor and
output cursor move to the corresponding position on the selected page.</P>
<P>Entering or exiting ReGIS does not change the currently displayed page. When
you enter ReGIS, the currently displayed graphics page is the same as the previously
displayed text page. The active graphics page is the same page as the
last time you exited ReGIS. If you did not use ReGIS since last resetting the terminal,
the active graphics page is the first graphics page.</P>
<P>When you exit ReGIS, the currently displayed text page is the same
as the previously displayed graphics page. The active text page is the same
page as the last time you used text mode.</P>
<P>When you exit ReGIS, the displayed text page becomes the same as the active
text page (if the <B>Page Coupling</B> feature on the Display Set-Up screen is
enabled).</P>
<H2 ID="S4.4">Position Command Summary</H2>
<P><A HREF="#T4-1">Table 4-1</A> is a summary of the <B>P</B> command arguments, including any default
values.</P>
<TABLE ID="T4-1" CLASS="summarytable" FRAME="VOID" RULES="GROUPS" CELLSPACING="0" CELLPADDING="4">
<CAPTION>Table 4-1 Position Command Summary</CAPTION>
<COL SPAN="2" WIDTH="25%">
<COL WIDTH="50%">
<THEAD>
<TR VALIGN="BOTTOM">
<TH>Argument</TH>
<TH>Default</TH>
<TH>Description</TH>
</TR>
</THEAD>
<TBODY>
<TR VALIGN="TOP">
<TD>[X,Y]</TD>
<TD>[0,0]</TD>
<TD><P><STRONG>Cursor positioning with [X,Y] values</STRONG><BR>
The [X,Y] values can be absolute, relative, or absolute/relative screen coordinates.</P></TD>
</TR>
<TR VALIGN="TOP">
<TD>&lt;PV&gt;</TD>
<TD>None</TD>
<TD><P><STRONG>Cursor positioning with PV values</STRONG><BR>
The pixel vector values select a direction and distance to move, relative to the current cursor position.</P></TD>
</TR>
<TR VALIGN="TOP">
<TD>(W(M&lt;n&gt;))</TD>
<TD>1</TD>
<TD><P><STRONG>PV multiplier</STRONG><BR>
This temporary write control option selects a multiplication factor for PV values. This factor defines
the number of coordinates to move for each PV value.</P></TD>
</TR>
<TR VALIGN="TOP">
<TD>(B)</TD>
<TD>None</TD>
<TD><P><STRONG>Begin a bounded position stack</STRONG><BR>
Pushes the current active position onto the stack. This position becomes the active position again after
a corresponding (E) option in the stack.</P></TD>
</TR>
<TR VALIGN="TOP">
<TD>(S)</TD>
<TD>None</TD>
<TD><P><STRONG>Start an unbounded position stack</STRONG><BR>
Pushes a dummy position onto the stack. When ReGIS reaches an (E) option in the stack, the active
position stays at its current location.</P></TD>
</TR>
<TR VALIGN="TOP">
<TD>(E)</TD>
<TD>None</TD>
<TD><P><STRONG>End of bounded or unbounded position stack</STRONG><BR>
Selects the active position at the end of a position stack. The active position is based on the
corresponding (B) option in a bounded stack or (S) option in an unbounded stack.</P></TD>
</TR>
<TR VALIGN="TOP">
<TD>(P&lt;pn&gt;)</TD>
<TD>None</TD>
<TD><P><STRONG>Select graphics page option</STRONG><BR>
Moves the cursor from the current page to page &lt;pn&gt; in graphics page memory, where &lt;pn&gt; is 0 or 1.</P></TD>
</TR>
</TBODY>
</TABLE>
<DIV CLASS="navbar"><HR>
<TABLE WIDTH="100%">
<COL SPAN="3" WIDTH="33%">
<TBODY>
<TR>
<TD ALIGN="LEFT"><A HREF="chapter3.html">Chapter 3</A></TD>
<TD ALIGN="CENTER"><A HREF="contents.html">Contents</A></TD>
<TD ALIGN="RIGHT"><A HREF="chapter5.html">Chapter 5</A></TD>
</TR>
</TBODY>
</TABLE>
<DIV CLASS="navbot">http://vt100.net/docs/vt3xx-gp/chapter4.html</DIV></DIV>
</BODY>
</HTML>
